<?php

namespace Kunfeng\Dify\Client;

use Kunfeng\Dify\Exception\DifyApiException;
use Kunfeng\Dify\Model\Chat\AppInfoResponse;
use Kunfeng\Dify\Model\Chat\AppParametersResponse;
use Kunfeng\Dify\Model\Chat\AppWebAppSettingResponse;
use Kunfeng\Dify\Model\File\FileUploadRequest;
use Kunfeng\Dify\Model\File\FileUploadResponse;
use Kunfeng\Dify\Model\File\FilePreviewResponse;

/**
 * Dify 基础客户端接口
 * 包含所有客户端共用的基础功能
 */
interface DifyBaseClientInterface
{
    /**
     * 上传文件
     *
     * @param string|FileUploadRequest $fileOrRequest 文件路径或上传请求
     * @param string|resource $filePathOrStream 文件路径或流
     * @param string|null $user 用户标识
     * @return FileUploadResponse
     * @throws DifyApiException
     */
    public function uploadFile(
        $fileOrRequest, 
        $filePathOrStream, 
        ?string $user = null
    ): FileUploadResponse;

    /**
     * 获取应用基本信息
     *
     * @return AppInfoResponse
     * @throws DifyApiException
     */
    public function getAppInfo(): AppInfoResponse;

    /**
     * 获取应用参数
     *
     * @return AppParametersResponse
     * @throws DifyApiException
     */
    public function getAppParameters(): AppParametersResponse;

    /**
     * 获取应用 WebApp 设置
     *
     * @return AppWebAppSettingResponse
     * @throws DifyApiException
     */
    public function getAppWebAppSettings(): AppWebAppSettingResponse;

    /**
     * 预览文件
     * 预览或下载已上传的文件。文件只能在属于请求应用程序的消息范围内访问。
     *
     * @param string $fileId 文件ID，从文件上传 API 响应中获得的唯一标识符
     * @param bool $asAttachment 是否强制将文件作为附件下载，默认为 false（在浏览器中预览）
     * @return FilePreviewResponse
     * @throws DifyApiException
     */
    public function previewFile(string $fileId, bool $asAttachment = false): FilePreviewResponse;

    /**
     * 关闭客户端资源
     */
    public function close(): void;
}
